[[beans-definition]]
= Bean Overview

A Spring IoC container manages one or more beans. These beans are created with the
configuration metadata that you supply to the container (for example, in the form of XML
`<bean/>` definitions).

Within the container itself, these bean definitions are represented as `BeanDefinition`
objects, which contain (among other information) the following metadata:

* A package-qualified class name: typically, the actual implementation class of the
  bean being defined.
* Bean behavioral configuration elements, which state how the bean should behave in the
  container (scope, lifecycle callbacks, and so forth).
* References to other beans that are needed for the bean to do its work. These
  references are also called collaborators or dependencies.
* Other configuration settings to set in the newly created object -- for example, the size
  limit of the pool or the number of connections to use in a bean that manages a
  connection pool.

This metadata translates to a set of properties that make up each bean definition.
The following table describes these properties:

[[beans-factory-bean-definition-tbl]]
.The bean definition
|===
| Property| Explained in...

| Class
| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans]

| Name
| xref:core/beans/definition.adoc#beans-beanname[Naming Beans]

| Scope
| xref:core/beans/factory-scopes.adoc[Bean Scopes]

| Constructor arguments
| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]

| Properties
| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]

| Autowiring mode
| xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]

| Lazy initialization mode
| xref:core/beans/dependencies/factory-lazy-init.adoc[Lazy-initialized Beans]

| Initialization method
| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[Initialization Callbacks]

| Destruction method
| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[Destruction Callbacks]
|===

In addition to bean definitions that contain information on how to create a specific
bean, the `ApplicationContext` implementations also permit the registration of existing
objects that are created outside the container (by users). This is done by accessing the
ApplicationContext's `BeanFactory` through the `getBeanFactory()` method, which returns
the `DefaultListableBeanFactory` implementation. `DefaultListableBeanFactory` supports
this registration through the `registerSingleton(..)` and `registerBeanDefinition(..)`
methods. However, typical applications work solely with beans defined through regular
bean definition metadata.

[NOTE]
====
Bean metadata and manually supplied singleton instances need to be registered as early
as possible, in order for the container to properly reason about them during autowiring
and other introspection steps. While overriding existing metadata and existing
singleton instances is supported to some degree, the registration of new beans at
runtime (concurrently with live access to the factory) is not officially supported and may
lead to concurrent access exceptions, inconsistent state in the bean container, or both.
====



[[beans-definition-overriding]]
== Overriding Beans

Bean overriding occurs when a bean is registered using an identifier that is already
allocated. While bean overriding is possible, it makes the configuration harder to read.

WARNING: Bean overriding will be deprecated in a future release.

To disable bean overriding altogether, you can set the `allowBeanDefinitionOverriding`
flag to `false` on the `ApplicationContext` before it is refreshed. In such a setup, an
exception is thrown if bean overriding is used.

By default, the container logs every attempt to override a bean at `INFO` level so that
you can adapt your configuration accordingly. While not recommended, you can silence
those logs by setting the `allowBeanDefinitionOverriding` flag to `true`.

.Java Configuration
****
If you use Java Configuration, a corresponding `@Bean` method always silently overrides
a scanned bean class with the same component name as long as the return type of the
`@Bean` method matches that bean class. This simply means that the container will call
the `@Bean` factory method in favor of any pre-declared constructor on the bean class.
****

NOTE: We acknowledge that overriding beans in test scenarios is convenient, and there is
explicit support for this as of Spring Framework 6.2. Please refer to
xref:testing/testcontext-framework/bean-overriding.adoc[this section] for more details.



[[beans-beanname]]
== Naming Beans

Every bean has one or more identifiers. These identifiers must be unique within the
container that hosts the bean. A bean usually has only one identifier. However, if it
requires more than one, the extra ones can be considered aliases.

In XML-based configuration metadata, you use the `id` attribute, the `name` attribute, or
both to specify bean identifiers. The `id` attribute lets you specify exactly one `id`.
Conventionally, these names are alphanumeric ('myBean', 'someService', etc.), but they
can contain special characters as well. If you want to introduce other aliases for the
bean, you can also specify them in the `name` attribute, separated by a comma (`,`),
semicolon (`;`), or white space. Although the `id` attribute is defined as an
`xsd:string` type, bean `id` uniqueness is enforced by the container, though not by XML
parsers.

You are not required to supply a `name` or an `id` for a bean. If you do not supply a
`name` or `id` explicitly, the container generates a unique name for that bean. However,
if you want to refer to that bean by name, through the use of the `ref` element or a
Service Locator style lookup, you must provide a name.
Motivations for not supplying a name are related to using xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-inner-beans[inner beans]
 and xref:core/beans/dependencies/factory-autowire.adoc[autowiring collaborators].

.Bean Naming Conventions
****
The convention is to use the standard Java convention for instance field names when
naming beans. That is, bean names start with a lowercase letter and are camel-cased
from there. Examples of such names include `accountManager`,
`accountService`, `userDao`, `loginController`, and so forth.

Naming beans consistently makes your configuration easier to read and understand.
Also, if you use Spring AOP, it helps a lot when applying advice to a set of beans
related by name.
****

NOTE: With component scanning in the classpath, Spring generates bean names for unnamed
components, following the rules described earlier: essentially, taking the simple class name
and turning its initial character to lower-case. However, in the (unusual) special
case when there is more than one character and both the first and second characters
are upper case, the original casing gets preserved. These are the same rules as
defined by `java.beans.Introspector.decapitalize` (which Spring uses here).


[[beans-beanname-alias]]
=== Aliasing a Bean outside the Bean Definition

In a bean definition itself, you can supply more than one name for the bean, by using a
combination of up to one name specified by the `id` attribute and any number of other
names in the `name` attribute. These names can be equivalent aliases to the same bean
and are useful for some situations, such as letting each component in an application
refer to a common dependency by using a bean name that is specific to that component
itself.

Specifying all aliases where the bean is actually defined is not always adequate,
however. It is sometimes desirable to introduce an alias for a bean that is defined
elsewhere. This is commonly the case in large systems where configuration is split
amongst each subsystem, with each subsystem having its own set of object definitions.
In XML-based configuration metadata, you can use the `<alias/>` element to accomplish
this. The following example shows how to do so:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<alias name="fromName" alias="toName"/>
----

In this case, a bean (in the same container) named `fromName` may also,
after the use of this alias definition, be referred to as `toName`.

For example, the configuration metadata for subsystem A may refer to a DataSource by the
name of `subsystemA-dataSource`. The configuration metadata for subsystem B may refer to
a DataSource by the name of `subsystemB-dataSource`. When composing the main application
that uses both these subsystems, the main application refers to the DataSource by the
name of `myApp-dataSource`. To have all three names refer to the same object, you can
add the following alias definitions to the configuration metadata:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<alias name="myApp-dataSource" alias="subsystemA-dataSource"/>
	<alias name="myApp-dataSource" alias="subsystemB-dataSource"/>
----

Now each component and the main application can refer to the dataSource through a name
that is unique and guaranteed not to clash with any other definition (effectively
creating a namespace), yet they refer to the same bean.

.Java-configuration
****
If you use Java Configuration, the `@Bean` annotation can be used to provide aliases.
See xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] for details.
****



[[beans-factory-class]]
== Instantiating Beans

A bean definition is essentially a recipe for creating one or more objects. The
container looks at the recipe for a named bean when asked and uses the configuration
metadata encapsulated by that bean definition to create (or acquire) an actual object.

If you use XML-based configuration metadata, you specify the type (or class) of object
that is to be instantiated in the `class` attribute of the `<bean/>` element. This
`class` attribute (which, internally, is a `Class` property on a `BeanDefinition`
instance) is usually mandatory. (For exceptions, see
xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[Instantiation by Using an Instance Factory Method] and xref:core/beans/child-bean-definitions.adoc[Bean Definition Inheritance].)
You can use the `Class` property in one of two ways:

* Typically, to specify the bean class to be constructed in the case where the container
  itself directly creates the bean by calling its constructor reflectively, somewhat
  equivalent to Java code with the `new` operator.
* To specify the actual class containing the `static` factory method that is
  invoked to create the object, in the less common case where the container invokes a
  `static` factory method on a class to create the bean. The object type returned
  from the invocation of the `static` factory method may be the same class or another
  class entirely.

.Nested class names
****
If you want to configure a bean definition for a nested class, you may use either the
binary name or the source name of the nested class.

For example, if you have a class called `SomeThing` in the `com.example` package, and
this `SomeThing` class has a `static` nested class called `OtherThing`, they can be
separated by a dollar sign (`$`) or a dot (`.`). So the value of the `class` attribute in
a bean definition would be `com.example.SomeThing$OtherThing` or
`com.example.SomeThing.OtherThing`.
****


[[beans-factory-class-ctor]]
=== Instantiation with a Constructor

When you create a bean by the constructor approach, all normal classes are usable by and
compatible with Spring. That is, the class being developed does not need to implement
any specific interfaces or to be coded in a specific fashion. Simply specifying the bean
class should suffice. However, depending on what type of IoC you use for that specific
bean, you may need a default (empty) constructor.

The Spring IoC container can manage virtually any class you want it to manage. It is
not limited to managing true JavaBeans. Most Spring users prefer actual JavaBeans with
only a default (no-argument) constructor and appropriate setters and getters modeled
after the properties in the container. You can also have more exotic non-bean-style
classes in your container. If, for example, you need to use a legacy connection pool
that absolutely does not adhere to the JavaBean specification, Spring can manage it as
well.

With XML-based configuration metadata you can specify your bean class as follows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="exampleBean" class="examples.ExampleBean"/>

	<bean name="anotherExample" class="examples.ExampleBeanTwo"/>
----

For details about the mechanism for supplying arguments to the constructor (if required)
and setting object instance properties after the object is constructed, see
xref:core/beans/dependencies/factory-collaborators.adoc[Injecting Dependencies].

NOTE: In the case of constructor arguments, the container can select a corresponding
constructor among several overloaded constructors. That said, to avoid ambiguities,
it is recommended to keep your constructor signatures as straightforward as possible.


[[beans-factory-class-static-factory-method]]
=== Instantiation with a Static Factory Method

When defining a bean that you create with a static factory method, use the `class`
attribute to specify the class that contains the `static` factory method and an attribute
named `factory-method` to specify the name of the factory method itself. You should be
able to call this method (with optional arguments, as described later) and return a live
object, which subsequently is treated as if it had been created through a constructor.
One use for such a bean definition is to call `static` factories in legacy code.

The following bean definition specifies that the bean will be created by calling a
factory method. The definition does not specify the type (class) of the returned object,
but rather the class containing the factory method. In this example, the
`createInstance()` method must be a `static` method. The following example shows how to
specify a factory method:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="clientService"
		class="examples.ClientService"
		factory-method="createInstance"/>
----

The following example shows a class that would work with the preceding bean definition:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
----
	public class ClientService {
		private static ClientService clientService = new ClientService();
		private ClientService() {}

		public static ClientService createInstance() {
			return clientService;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
----
	class ClientService private constructor() {
		companion object {
			private val clientService = ClientService()
			@JvmStatic
			fun createInstance() = clientService
		}
	}
----
======

For details about the mechanism for supplying (optional) arguments to the factory method
and setting object instance properties after the object is returned from the factory,
see xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail].

NOTE: In the case of factory method arguments, the container can select a corresponding
method among several overloaded methods of the same name. That said, to avoid ambiguities,
it is recommended to keep your factory method signatures as straightforward as possible.

[TIP]
====
A typical problematic case with factory method overloading is Mockito with its many
overloads of the `mock` method. Choose the most specific variant of `mock` possible:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="clientService" class="org.mockito.Mockito" factory-method="mock">
		<constructor-arg type="java.lang.Class" value="examples.ClientService"/>
		<constructor-arg type="java.lang.String" value="clientService"/>
	</bean>
----
====


[[beans-factory-class-instance-factory-method]]
=== Instantiation by Using an Instance Factory Method

Similar to instantiation through a xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static factory method]
, instantiation with an instance factory method invokes a non-static
method of an existing bean from the container to create a new bean. To use this
mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute,
specify the name of a bean in the current (or parent or ancestor) container that contains
the instance method that is to be invoked to create the object. Set the name of the
factory method itself with the `factory-method` attribute. The following example shows
how to configure such a bean:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<!-- the factory bean, which contains a method called createClientServiceInstance() -->
	<bean id="serviceLocator" class="examples.DefaultServiceLocator">
		<!-- inject any dependencies required by this locator bean -->
	</bean>

	<!-- the bean to be created via the factory bean -->
	<bean id="clientService"
		factory-bean="serviceLocator"
		factory-method="createClientServiceInstance"/>
----

The following example shows the corresponding class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
----
	public class DefaultServiceLocator {

		private static ClientService clientService = new ClientServiceImpl();

		public ClientService createClientServiceInstance() {
			return clientService;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
----
	class DefaultServiceLocator {
		companion object {
			private val clientService = ClientServiceImpl()
		}
		fun createClientServiceInstance(): ClientService {
			return clientService
		}
	}
----
======

One factory class can also hold more than one factory method, as the following example shows:

[source,xml,indent=0,subs="verbatim,quotes"]
----
	<bean id="serviceLocator" class="examples.DefaultServiceLocator">
		<!-- inject any dependencies required by this locator bean -->
	</bean>

	<bean id="clientService"
		factory-bean="serviceLocator"
		factory-method="createClientServiceInstance"/>

	<bean id="accountService"
		factory-bean="serviceLocator"
		factory-method="createAccountServiceInstance"/>
----

The following example shows the corresponding class:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
----
	public class DefaultServiceLocator {

		private static ClientService clientService = new ClientServiceImpl();

		private static AccountService accountService = new AccountServiceImpl();

		public ClientService createClientServiceInstance() {
			return clientService;
		}

		public AccountService createAccountServiceInstance() {
			return accountService;
		}
	}
----

Kotlin::
+
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
----
	class DefaultServiceLocator {
		companion object {
			private val clientService = ClientServiceImpl()
			private val accountService = AccountServiceImpl()
		}

		fun createClientServiceInstance(): ClientService {
			return clientService
		}

		fun createAccountServiceInstance(): AccountService {
			return accountService
		}
	}
----
======

This approach shows that the factory bean itself can be managed and configured through
dependency injection (DI).
See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail].

NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the
Spring container and that creates objects through an
xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[instance] or
xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static] factory method. By contrast,
`FactoryBean` (notice the capitalization) refers to a Spring-specific
xref:core/beans/factory-extension.adoc#beans-factory-extension-factorybean[`FactoryBean`] implementation class.


[[beans-factory-type-determination]]
=== Determining a Bean's Runtime Type

The runtime type of a specific bean is non-trivial to determine. A specified class in
the bean metadata definition is just an initial class reference, potentially combined
with a declared factory method or being a `FactoryBean` class which may lead to a
different runtime type of the bean, or not being set at all in case of an instance-level
factory method (which is resolved via the specified `factory-bean` name instead).
Additionally, AOP proxying may wrap a bean instance with an interface-based proxy with
limited exposure of the target bean's actual type (just its implemented interfaces).

The recommended way to find out about the actual runtime type of a particular bean is
a `BeanFactory.getType` call for the specified bean name. This takes all of the above
cases into account and returns the type of object that a `BeanFactory.getBean` call is
going to return for the same bean name.


